package com.xrui.hbase;

import java.io.Closeable;
import java.io.IOException;
import java.util.Iterator;

/**
 * Interface for scanning over rows read from a HBase table.
 * <p>
 * <p>
 * The row scanner behaves like an iterator over the rows in a HBase table.
 * The scanner implements the Java Iterable interface, so you can write code like this:
 * <pre>{@code
 *     RowScanner scanner = tableReader.getScanner(...);
 *     try {
 *       for (RowData row : scanner) {
 *         process(row);
 *       }
 *     } finally {
 *       // Always close resources:
 *       scanner.close();
 *     }
 *   }</pre>
 * <p>
 * <p>
 * Note: the scanner is backed by a single iterator:
 * {@link RowScanner#iterator()} returns the same iterator always.
 * As a result, the scanner and its iterator should not be used simultaneously from multiple
 * places (eg. from multiple threads).
 * Similarly, when chaining two for loops on the same row scanner, the second for loop will
 * restart where the first for loop stopped.
 * </p>.
 */
public interface RowScanner extends Closeable, Iterable<RowData> {

    /**
     * Returns the iterator over HBase rows backing this scanner.
     * <p>
     * <p>
     * Always returns the same iterator.
     * As a result, the scanner and its iterator should not be used simultaneously from multiple
     * places (eg. from multiple threads).
     * Similarly, when chaining two for loops on the same row scanner, the second for loop will
     * restart where the first for loop stopped.
     * </p>
     *
     * @return the iterator over HBase rows backing this scanner.
     */
    @Override
    Iterator<RowData> iterator();

    /**
     * Closes this scanner and releases any system resources associated with it.
     * <p>
     * <p>Calling this method when you are finished with the scanner is important.
     * See http://hbase.apache.org/book.html#perf.hbase.client.scannerclose for details.</p>
     *
     * @throws IOException If an I/O error occurs.
     */
    @Override
    void close() throws IOException;
}
